<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="rustdoc">
    <title>Native Windows GUI guide - Dialogs</title>

    <link rel="stylesheet" type="text/css" href="style/rustbook.css">
    <link rel="stylesheet" type="text/css" href="style/pygments.css">
    <link rel="stylesheet" type="text/css" href="style/nwg.css">

</head>
<body class="rustdoc">
<!--[if lte IE 8]>
<div class="warning">
    This old browser is unsupported and will most likely display funky
    things.
</div>
<![endif]-->

<!-- NAV BEGIN -->
<div id="nav">
    <button id="toggle-nav">
        <span class="sr-only">Toggle navigation</span>
        <span class="bar"></span>
        <span class="bar"></span>
        <span class="bar"></span>
    </button>
</div>

    
<div id='toc' class='mobile-hidden'>
<ul class='chapter'>
<li><a href='index.html'><b>1.</b> Introduction</a>
</li>
<li><a href='getting_started.html'><b>2.</b> Getting Started</a>
</li>

<li><a href="basics.html"><b>3.</b> Basics </a>
<ul class="section">
    <li><a href="controls.html"><b>3.1.</b> Controls </a></li>
    <li><a href="events.html"><b>3.2.</b> Events </a></li>
    <li><a href="helper.html"><b>3.3.</b> Helpers </a></li>
    <li><a href="small.html"><b>3.4.</b> Small application layout </a></li>
    <li><a href="limitations.html"><b>3.5.</b> Limitations </a></li>
    <li><a href="distribute.html"><b>3.6.</b> Distributing </a></li>
    <li><a href="features.html"><b>3.7.</b> Features </a></li>
</ul>
</li>

<li><a href="intermediate.html"><b>4.</b> Intermediate </a>
<ul class="section">
    <li><a href="layouts.html"><b>4.1.</b> Layouts </a></li>
    <li><a href="resources.html"><b>4.2.</b> Resources </a></li>
    <li><a href="dialogs.html"><b>4.3.</b> Dialogs </a></li>
    <li><a href="localization.html"><b>4.4.</b> Internationalization </a></li>
</ul>
</li>

<li><a href="advanced.html"><b>5.</b> Advanced </a>
<ul class="section">
    <li><a href="partial.html"><b>5.1.</b> Partials ui </a></li>
    <li><a href="dynamic_control.html"><b>5.2.</b> Dynamic control </a></li>
    <li><a href="dynamic_event.html"><b>5.3.</b> Dynamic events </a></li>
    <li><a href="multithreading.html"><b>5.4.</b> Multithreading </a></li>
</ul>
</li>

<li><a href="derive.html"><b>6.</b> Native-windows-derive </a>
<ul class="section">
    <li><a href="nwd_basics.html"><b>6.1.</b> Basics </a></li>
    <li><a href="nwd_controls.html"><b>6.1.</b> Controls </a></li>
    <li><a href="nwd_resources.html"><b>6.2.</b> Resources </a></li>
    <li><a href="nwd_events.html"><b>6.3.</b> Events </a></li>
    <li><a href="nwd_layouts.html"><b>6.4.</b> Layouts </a></li>
    <li><a href="nwd_partial.html"><b>6.5.</b> Partials </a></li>
</ul>
</li>

<li><a href="low.html"><b>7.</b> Low level stuff </a>
    <ul class="section">
        <li><a href="low_events.html"><b>7.1.</b> Raw event handling </a></li>
        <li><a href="extern_wrapping.html"><b>7.2.</b> Raw control handle </a></li>
    </ul>
</li>

</ul>
</div>
<!-- NAV END -->

<div id='page-wrapper'>
    <div id='page'>

        <h1 class="title">Native Windows GUI: Dialogs</h1>
        Dialogs are premade window that returns values.<br><br>
        Dialogs are not required for every application, as such they are all feature-gated.<br>
        Native windows GUI includes 3 builtin dialogs:<br>

        <ul>
            <li>FileDialog (feature: <code>file-dialog</code>): fetch file path to load or save something</li>
            <li>ColorDialog (feature: <code>color-dialog</code>): fetch and saves color data in a RGB format</li>
            <li>FontDialog (feature: <code>font-dialog</code>): select a system font with optional customization</li>
        </ul>

        See the <a href="https://github.com/gabdube/native-windows-gui/tree/master/showcase">Showcase</a> for the dialog looks
        And see <a href="https://github.com/gabdube/native-windows-gui/blob/master/native-windows-gui/examples/image_decoder_d.rs">the examples</a> for a code example
        <br><br>

        <h3>Basic usage</h3>

        Dialogs are <b>resources</b> and not controls.<br><br>
        Because of this, dialogs do not need a parent and they cannot accept children.<br>

        Just like the other NWG components, dialogs are created with builders. The documentation enumerates their parameters.<br><br>

        Dialogs are called by using the method <code>run(parent)</code>.
        This method <b>will block the current function</b>. This is because dialogs have their own events loop. Because of this, the other window
        in the same thread should be disabled while the dialog is running. This is done automatically setting the parent parameter in a dialog.
        <br><br>

        Once the user selects a value, the selected value will be saved in the dialog object. Each dialog has a specific method to fetch this data.<br>

<div class="highlight"><pre style="width: auto;"><span></span><span class="k">if</span><span class="w"> </span><span class="n">app</span><span class="p">.</span><span class="n">open_directory_dialog</span><span class="p">.</span><span class="n">run</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="n">app</span><span class="p">.</span><span class="n">file_dialog_result</span><span class="p">.</span><span class="n">clear</span><span class="p">();</span><span class="w"></span>
<span class="w">    </span><span class="k">if</span><span class="w"> </span><span class="kd">let</span><span class="w"> </span><span class="nb">Ok</span><span class="p">(</span><span class="n">directory</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">app</span><span class="p">.</span><span class="n">open_directory_dialog</span><span class="p">.</span><span class="n">get_selected_item</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="n">app</span><span class="p">.</span><span class="n">file_dialog_result</span><span class="p">.</span><span class="n">set_text</span><span class="p">(</span><span class="o">&amp;</span><span class="n">directory</span><span class="p">);</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>


        <h3>File dialog</h3>
        <img src="https://raw.githubusercontent.com/gabdube/native-windows-gui/master/showcase/file_dialog.png" style="width: 500px" />
        <br><br>

        FileDialog uses the common item dialog (<a href="https://docs.microsoft.com/en-us/previous-versions/windows/desktop/legacy/bb776913(v=vs.85)?redirectedfrom=MSDN">link</a>)
        It supports the <code>FileDialogAction::Open</code>, <code>FileDialogAction::OpenDirectory</code> and <code>FileDialogAction::Save</code>.
        <br><br>

        A file dialog can accept multiple files if the <code>multiselect</code> flag is set in the builder. The multiselect flag can also be changed
        with the <code>set_multiselect</code> method. The multi select flag can only be used with opening dialogs.
        <br><br>

        To display a FileDialog, call <code>dialog.run(parent)</code>. Just like the other dialog, this will start a new event loop.
        <br><br>

        To fetch the results of a file dialog, use the <code>dialog.get_selected_item()</code> for single select file dialog and
        <code>dialog.get_selected_items()</code> for multi select file dialog. Calling the wrong method will return an Error.
        <br><br>


        <h3>Color dialog</h3>
        <img src="https://raw.githubusercontent.com/gabdube/native-windows-gui/master/showcase/color_dialog.png" style="width: 500px" />
        <br><br>

        A color dialog returns a color in a [R,G,B] format. The values will range from <code>[0u8, 0u8, 0u8]</code> (black)
        to <code>[255, 255, 255]</code> (white).
        <br><br>

        To display a ColorDialog, call <code>dialog.run(parent)</code>. Although it is optional, you should specify a window as parent. Just like the other dialog, this will start a new event loop.
        <br><br>

        To fetch the results of a color dialog, use the <code>dialog.color()</code> method.
        <br><br>

        The color dialog allows the developer or the user to save up to 16 custom colors per dialogs. The user sets the color using the dialog interface, and the 
        developer can set/get the colors using <code>set_saved_color(index, color)</code> or <code>saved_color(index)</code>. 
        <br><br>

        Set the saved colors in the <b>color dialog builder</b> using the <code>saved_color(index, color)</code> method.

        <h3>Font dialog</h3>
        <img src="https://raw.githubusercontent.com/gabdube/native-windows-gui/master/showcase/font_dialog.png" style="height: 400px" />
        <br><br>

        A font dialog returns a <code>FontInfo</code> object that describes the font selected by the user <b>(not a font resource)</b>.<br>
        <br><br>

        To display a FontDialog, call <code>dialog.run(parent)</code>. Although it is optional, you should specify a window as parent. Just like the other dialog, this will start a new event loop.
        <br><br>

        To fetch the results of a color dialog, use the <code>dialog.font()</code> method.
        <br><br>

        The font info can then be used to create font resources. Note that the default font resource provided by NWG is very simple and only supports
        a size, a family and a weight.

        <h3>Custom dialog</h3>

        Native windows gui does not use the default win32 way to handle custom dialogs because it involves use resource files, and worse, dialogs runs in another message loop in the same thread.
        Instead, user dialogs should be implemented as normal GUI object running in another thread. For an example see: <a href="https://github.com/gabdube/native-windows-gui/blob/master/native-windows-gui/examples/dialog_multithreading_d.rs">the dialog example</a>

        <br><br>
        <br><br>

    </div>
</div>

<script src="style/rustbook.js"></script>
</body>
</html>
